<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Lock Modes - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level2"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<p class="toc level2"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level2"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level2"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level3"><a href="gkjhz.html">Overview of Entity Locking and Concurrency</a></p>
<p class="toc level4"><a href="gkjhz.html#gkjjc">Using Optimistic Locking</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3 tocsp"><a href="">Lock Modes</a></p>
<p class="toc level4"><a href="#gkjik">Setting the Lock Mode</a></p>
<p class="toc level4"><a href="#gkjil">Using Pessimistic Locking</a></p>
<p class="toc level5"><a href="#gkjlq">Pessimistic Locking Timeouts</a></p>
</div>
<p class="toc level2 tocsp"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level2"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level2"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="gkjhz.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="gkjia.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="gkjiu"></a><h2>Lock Modes</h2>
<p>The application may increase the level of locking for an entity by
specifying the use of lock modes.  Lock modes may be specified to
increase the level of optimistic locking or to request the use of pessimistic
locks.</p>

<p>The use of optimistic lock modes causes the persistence provider to check the
version attributes for entities that were read (but not modified) during a transaction
as well as for those entities that were updated.</p>

<p>The use of pessimistic lock modes specifies that the persistence provider is to
immediately acquire long-term read or write locks for the database data corresponding to
entity state.</p>

<p>The lock mode for an entity operation may be set by specifying
one of the lock modes defined in the <tt>javax.persistence.LockModeType</tt> enumerated type, listed in <a href="#gkjie">Table&nbsp;37-1</a>.</p>

<a name="gkjie"></a><p class="caption">Table&nbsp;37-1 Lock Modes for Concurrent Entity Access</p><table><col width="50%"><col width="50%"><tr><th align="left" valign="top" scope="column"><p>Lock
Mode</p>

</th>
<th align="left" valign="top" scope="column"><p>Description</p>

</th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>OPTIMISTIC</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Obtain an optimistic read lock for all entities with a version attribute.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>OPTIMISTIC_FORCE_INCREMENT</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Obtain
an optimistic read lock for all entities with a version attribute, and increment
the version attribute value.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>PESSIMISTIC_READ</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Immediately obtain a long-term read lock on the data
to prevent the data from being modified or deleted. Other transactions may read
the data while the lock is maintained, but may not modify or delete
the data.</p>

<p>The persistence provider is permitted to obtain a database write lock when
a read lock was requested, but not vice versa.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>PESSIMISTIC_WRITE</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Immediately obtain a long-term
write lock on the data to prevent the data from being read, modified,
or deleted. </p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>PESSIMISTIC_FORCE_INCREMENT</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>Immediately obtain a long-term lock on the data to prevent
the data from being modified or deleted, and increment the version attribute of
versioned entities.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>READ</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>A synonym for <tt>OPTIMISTIC</tt>. Use of <tt>LockModeType.OPTIMISTIC</tt> is to be preferred for
new applications.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>WRITE</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>A synonym for <tt>OPTIMISTIC_FORCE_INCREMENT</tt>. Use of <tt>LockModeType.OPTIMISTIC_FORCE_INCREMENT</tt> is to be preferred
for new applications.</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>NONE</tt></p>

</td>
<td align="left" valign="top" scope="row"><p>No additional locking will occur on the data in the database.</p>

</td>
</tr>
</table>

<a name="gkjik"></a><h3>Setting the Lock Mode</h3>
<p>The lock mode may be specified by one of the following techniques:</p>


<ul><li><p>Calling the <tt>EntityManager.lock</tt> and passing in one of the lock modes:</p>

<pre>EntityManager em = ...;
Person person = ...;
em.lock(person, LockModeType.OPTIMISTIC);</pre></li>
<li><p>Calling one of the <tt>EntityManager.find</tt> methods that takes the lock mode as a parameter:</p>

<pre>EntityManager em = ...;
String personPK = ...;
Person person = em.find(Person.class, personPK, LockModeType.PESSIMISTIC_WRITE);</pre></li>
<li><p>Calling one of the <tt>EntityManager.refresh</tt> methods that takes the lock mode as a parameter:</p>

<pre>EntityManager em = ...;
String personPK = ...;
Person person = em.find(Person.class, personPK);
...
em.refresh(person, LockModeType.OPTIMISTIC_FORCE_INCREMENT);</pre></li>
<li><p>Calling the <tt>Query.setLockMode</tt> or <tt>TypedQuery.setLockMode</tt> method, passing the lock mode as the parameter:</p>

<pre>Query q = em.createQuery(...);
q.setLockMode(LockModeType.PESSIMISTIC_FORCE_INCREMENT);</pre></li>
<li><p>Adding a <tt>lockMode</tt> element to the <tt>@NamedQuery</tt> annotation:</p>

<pre>@NamedQuery(name="lockPersonQuery",
  query="SELECT p FROM Person p WHERE p.name LIKE :name",
  lockMode=PESSIMISTIC_READ)</pre></li></ul>


<a name="gkjil"></a><h3>Using Pessimistic Locking</h3>
<p>Versioned entities as well as entities that do not have a version
attribute can be locked pessimistically.</p>

<p>To lock entities pessimistically, set the lock mode to <tt>PESSIMISTIC_READ</tt>, <tt>PESSIMISTIC_WRITE</tt>, or
<tt>PESSIMISTIC_FORCE_INCREMENT</tt>.</p>

<p>If a pessimistic lock cannot be obtained on the database rows, and
the failure to lock the data results in a transaction rollback, a <tt>PessimisticLockException</tt>
is thrown. If a pessimistic lock cannot be obtained, but the locking failure
doesn't result in a transaction rollback, a <tt>LockTimeoutException</tt> is thrown.</p>

<p>Pessimistically locking a version entity with <tt>PESSIMISTIC_FORCE_INCREMENT</tt> results in the version attribute
being incremented, even if the entity data is unmodified. When pessimistically locking a
versioned entity, the persistence provider will perform the version checks that occur during optimistic
locking, and if the version check fails, an <tt>OptimisticLockException</tt> will be thrown.
Attempting to lock a non-versioned entity with <tt>PESSIMISTIC_FORCE_INCREMENT</tt> is not portable and
may result in a <tt>PersistenceException</tt> if the persistence provider doesn't support optimistic locks
for non-versioned entities. Locking a versioned entity with <tt>PESSIMISTIC_WRITE</tt> results in the
version attribute being incremented if the transaction was successfully committed.</p>



<a name="gkjlq"></a><h4>Pessimistic Locking Timeouts</h4>
<p>The length of time in milliseconds the persistence provider should wait to obtain
a lock on the database tables may be specified using the <tt>javax.persistence.lock.timeout</tt>
property. If the time it takes to obtain a lock exceeds the
value of this property, a <tt>LockTimeoutException</tt> will be thrown, but the current transaction will
not be marked for rollback. If this property is set to <tt>0</tt>, the
persistence provider should throw a <tt>LockTimeoutException</tt> if it cannot immediately obtain a
lock.</p>


<hr><p><b>Note - </b>Portable applications should not rely on the setting of <tt>javax.persistence.lock.timeout</tt>, as the
locking strategy and underlying database may mean that the timeout value cannot be
used. The value of <tt>javax.persistence.lock.timeout</tt> is a hint, not a contract.</p>


<hr>
<p>This property may be set programmatically by passing it to the <tt>EntityManager</tt>
methods that allow lock modes to be specified, the <tt>Query.setLockMode</tt> and <tt>TypedQuery.setLockMode</tt> methods,
the <tt>@NamedQuery</tt> annotation, and as a property to the <tt>Persistence.createEntityManagerFactory</tt> method. It may also
be set as a property in the <tt>persistence.xml</tt> deployment descriptor.</p>

<p>If <tt>javax.persistence.lock.timeout</tt> is set in multiple places, the value will be determined in
the following order:</p>


<ol><li><p>The argument to one of the <tt>EntityManager</tt> or <tt>Query</tt> methods.</p>

</li>
<li><p>The setting in the <tt>@NamedQuery</tt> annotation.</p>

</li>
<li><p>The argument to the <tt>Persistence.createEntityManagerFactory</tt> method.</p>

</li>
<li><p>The value in the <tt>persistence.xml</tt> deployment descriptor.</p>

</li></ol>

         </div>
         <div class="navigation">
             <a href="gkjhz.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="gkjia.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

